Accessibility-focused Unit Testing in Jest

In this section, we’ll become familiar with Jest by reading the source code for existing unit tests for the Icon component.

Open the icon.test.js file from inside the components/__tests__ directory, and follow along!

Reading Existing Icon Tests

At the very top of the file is a special docblock comment that tells Jest that we want to use jsdom as our test environment instead of the default Node.js environment. This allows us to write tests that behave as though we’re interacting with the DOM in a headless browser:

/**
 * @jest-environment jsdom
 */

/**
 * @jest-environment jsdom
 */

Next, we import React and some of the helpers from Testing Library:

• render
• screen
• getByText, getByLabelText, and getByRole

We will also import the Icon component that is the subject of our unit tests.

import React from 'react'
 import { render, getByRole, getByLabelText } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import userEvent from '@testing-library/user-event'
 
 import Icon from "../icon"

import React from 'react'
 import { render, getByRole, getByLabelText } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import userEvent from '@testing-library/user-event'
 
 import Icon from "../icon"

Jest uses describe() to group related tests in a named block.

For a string name in the describe statement we will match the component we’re testing and use Icon. The second argument to describe() is an arrow function with our test code.

Referencing the test() section in Jest’s docs, we can find that we need a name and a function to run the test. An optional third argument is a timeout for specifying how long to wait before aborting the test. We’ll stick with Jest’s default of 5 seconds (or more accurately, 5000 milliseconds).

The first test in this example looks to see if the Icon has a label when it is rendered. The second test will look for a role of img.

The code for the Icon tests is as follows:

describe('Icon', () =>{
     it('labels the icon', () => {
        const nameFixture = "dock"
        const { getByLabelText } = render(<Icon name={nameFixture} />)

        const iconText = getByLabelText(nameFixture)

        expect(iconText).toBeInTheDocument()
     })
     it('has an image role', () => {
        const {getByRole} = render(<Icon name="wifi" />)

        const icon = getByRole('img')

        expect(icon).toBeInTheDocument()
     })
})

describe('Icon', () =>{
     it('labels the icon', () => {
        const nameFixture = "dock"
        const { getByLabelText } = render(<Icon name={nameFixture} />)

        const iconText = getByLabelText(nameFixture)

        expect(iconText).toBeInTheDocument()
     })
     it('has an image role', () => {
        const {getByRole} = render(<Icon name="wifi" />)

        const icon = getByRole('img')

        expect(icon).toBeInTheDocument()
     })
})

The getByLabelText query from Testing Library looks for elements with a given label. In this test, if the rendered Icon has an aria-label of “dock” the test will pass. Similarly, getByRole is used to see if the Icon has a role of img.

Either of the tests would fail if the queries didn’t find any elements, but I prefer to explicitly include the expect.

More About Matchers

The expect() method in Jest is used to test for truthiness with some help from matchers.

You can compare numbers, objects, and more in a variety of ways. Check our their docs for the full list of matchers.

The jest-dom library builds on this concept and provides matchers with a focus on the DOM and accessibility. We use toBeInTheDocument() in the Icon test, but there are many more to choose from.

🛠 Challenge: Fix the Failing IconButton Label Test

There is a failing test for the IconButton component test file at components/__tests__/icon-button.test.js.

The failure message tells us that Jest isn’t able to find a label with the text of “Send it!"

Update the component code to make this test pass.

🛠 Solution: Fixing the Failing Label Test

Let’s start by taking a look at the test code.

// inside icon-button.test.js

describe('IconButton', () =>{
     it('labels the button', () => {
         const textFixture = "Send it!"
         const { getByLabelText } = render(<IconButton name={textFixture} />)
 
         const buttonText = getByLabelText(textFixture)
 
         expect(buttonText).toBeInTheDocument()
     })
 })

// inside icon-button.test.js

describe('IconButton', () =>{
     it('labels the button', () => {
         const textFixture = "Send it!"
         const { getByLabelText } = render(<IconButton name={textFixture} />)
 
         const buttonText = getByLabelText(textFixture)
 
         expect(buttonText).toBeInTheDocument()
     })
 })

Similar to before, we’re using the getByLabelText query to find a label in the rendered <IconButton> component.

Let’s look at the the source code for the component:

// components/icon-button.js
const IconButton = ({name, onClick}) => {
    return (
        <div
            className="btn-submit btn-lookingglass"
            data-testid="btn-submit"
            onClick={(event) => { onClick(event)}}
        >
            <span className="icon-lookingglass-white"></span>
        </div>
    )
}

// components/icon-button.js
const IconButton = ({name, onClick}) => {
    return (
        <div
            className="btn-submit btn-lookingglass"
            data-testid="btn-submit"
            onClick={(event) => { onClick(event)}}
        >
            <span className="icon-lookingglass-white"></span>
        </div>
    )
}

The first thing you might notice is that the component is using a div instead of a button element— but that won’t solve our failing test. We’ll come back to this in a minute.

Our test fails because it couldn’t find a label, and it ends up the name prop that we pass in isn’t being used.

Adding aria-label={name} will make our test pass.

const IconButton = ({name, onClick}) => {
    return (
        <div
            aria-label={name}
						...

const IconButton = ({name, onClick}) => {
    return (
        <div
            aria-label={name}
						...

Write New Tests for the IconButton

The <IconButton> component is used for the search button on the CampSpots homepage. When you use your keyboard to tab around the page, you’ll find that the button gets skipped over.

We’re going to add some new tests that make sure that the button is reachable and operable by the keyboard.

To help us trigger different types of events for testing user interactions, at the top of the test file we import user-event from Testing Library.

import userEvent from '@testing-library/user-event'

import userEvent from '@testing-library/user-event'

To set up userEvent, we need to call a setup function and store it in an arbitrary variable such as user.

const user = userEvent.setup()

const user = userEvent.setup()

Event calls like .tab() or .keyboard('[Enter]') will then hinge off of our stored variable.

Describe Tests Before Writing Them

Before diving into coding full tests, it can help to write the describe statements that reflect the behavior expected from the component you’re testing.

For accessibility unit tests, consider parts of the component’s API that impact user interaction and rendering of content inside the component. It’s a bit subjective how to divide up your tests but keeping them small and granular can make them easier to read.

For the button components, I expect that:

• The button has a label for users of Assistive Technology.
• The button can be reached with the keyboard
• The button can be operated with the keyboard and Assistive Tech.

We already know our button label works, so let’s write the reachability test.

Writing the Keyboard Operability Test

Following the structure of the existing test, add a new it() block and give it a description of the test we’ll be writing and and empty arrow function:

it('can be reached and operated with the keyboard', () => {

})

it('can be reached and operated with the keyboard', () => {

})

Since the component we’re testing is like a submit or “send” button, I’m going to use names and labels with variations on sending. Don’t be afraid to have some fun with your test data! (I like to work my pets’ names into every codebase I can. E.g. name=”Rainier McCheddarton”)

Render the Component

The first thing we’ll do inside is tell JestDOM to render the IconButton component along with some test data. I’ll use “Fling it” for the name.

We also need to supply an onClick handler function. I’ll use an anonymous arrow function that sets the value of a clicked variable to be true (I’ll initialize the clicked variable before the render call).

By writing the test logic this way, we’ll be able to test that the click handler fired the way we expect it to. We’d be able to write a test that checked for simulated mouse clicks as well as the keyboard hitting enter.

Here’s what it looks like so far:

it('can be operated with the keyboard and assistive tech', () => {
  let clicked = false
  render(<IconButton name="Fling it" onClick={()=> { clicked = true }} />)

it('can be operated with the keyboard and assistive tech', () => {
  let clicked = false
  render(<IconButton name="Fling it" onClick={()=> { clicked = true }} />)

Create a Reference to the Component

Now that our button will be rendered by jsdom, we need a reference to it in order to interact with it. There are numerous ways to query for an element in unit tests, such as getByTestId, getByRole, getByLabel, and many more. Which one you should choose will depend on the purpose of the test.

Looking at the markup for the IconButton component, we can find there is a data-testid attribute with a value of "btn-submit".

This is the attribute we will use to tell Testing Library what to look for by calling screen.getByRole:

const button = screen.getByRole('button')

const button = screen.getByRole('button')

Focus the Button & Simulate the Enter Key

Now we can call button.focus() to send focus to the button. If the button can’t be focused, the test will fail.

Once the button has focus, we will simulate a user hitting the enter key on the keyboard.

Simulating user input with the keyboard with user-event is asynchronous. This means we’ll need to add the async keyword to our test’s arrow function, then we can await the user.keyboard pressing the Enter key.

If everything works, the button will have its click handler fired so the clicked variable will be set to true.

Here’s what the test code looks like all together:

it('can be operated with the keyboard and assistive tech', async () => {
	let clicked = false
	render(<IconButton name="Fling it" onClick={()=> { clicked = true }} />)
        
	const button = screen.getByRole('button')

	button.focus()
	await user.keyboard('[Enter]')

	expect(clicked).toBe(true)
})

it('can be operated with the keyboard and assistive tech', async () => {
	let clicked = false
	render(<IconButton name="Fling it" onClick={()=> { clicked = true }} />)
        
	const button = screen.getByRole('button')

	button.focus()
	await user.keyboard('[Enter]')

	expect(clicked).toBe(true)
})

Now when we run Jest, the test fails because it can’t find an element with the role of button.

Fixing the Failed Operability Test

Here’s a reminder of what the IconButton component code currently looks like:

const IconButton = ({name, onClick}) => {
    return (
        <div
            aria-label={name}
            className="btn-submit btn-lookingglass"
            data-testid="btn-submit"
            onClick={(event) => { onClick(event)}}
        >
            <span className="icon-lookingglass-white"></span>
        </div>
    )
}

const IconButton = ({name, onClick}) => {
    return (
        <div
            aria-label={name}
            className="btn-submit btn-lookingglass"
            data-testid="btn-submit"
            onClick={(event) => { onClick(event)}}
        >
            <span className="icon-lookingglass-white"></span>
        </div>
    )
}

It might seem that adding role="button" would make the test pass, but that’s not how the browser works.

If you add the button role to the div-based IconButton, the test will still fail. This time it found the role, but there is no click handler that will toggle the clicked variable in the test!

If you were going to build a custom button component based on a div element, you would have to supply the role of button, set a tabindex of 0, and add a click handler.

But why do all of that work when you can use the semantic <button> element and get that functionality for free?

Changing the IconButton markup to use a <button> instead of a div will make the test pass as we want it to.

🛠 Challenge: Write a Separate Keyboard Reachability Test

The test we just wrote checks for both reachability and operability.

However, the reachability part of the test was just calling button.focus().

There is utility in having a a separate keyboard specific reachability test.

It might help catch issues related to screen reader modes, or cases where something with a tabindex of -1 was being tested.

Using the above tests as your guide, write a separate test to check that the IconButton is reachable by the keyboard.

Try using a different query than getByRole. Look at the component markup for ideas.

🛠 Solution: Writing a Keyboard Reachability Test

I’ll start by writing out a new it() with a description of “can be reached by the keyboard” along with the arrow function.

This time instead of using getByRole, I’ll use getByTestId and pass in a btn-submit string to match the component’s test-id attribute.

The User Event library offers a user.tab() shorthand to simulate pressing the tab key.

I’ll then use Jest’s expect() method and check the button with the toHaveFocus() matcher from jest-dom.

Here’s what my reachability test looks like:

it('can be reached with the keyboard', () => {
	render(<IconButton name="Chuck it" />)
	const button = screen.getByTestId('btn-submit')

	user.tab()

	expect(button).toHaveFocus()
})

it('can be reached with the keyboard', () => {
	render(<IconButton name="Chuck it" />)
	const button = screen.getByTestId('btn-submit')

	user.tab()

	expect(button).toHaveFocus()
})

Saving the file and running Jest, I can see that my test passes as expected.